From c9f1b9bf1e535a651f624897bd53a3f81af7501f Mon Sep 17 00:00:00 2001 From: Alex Crichton Date: Thu, 1 Oct 2015 10:26:33 -0700 Subject: [PATCH] Touch up docs and use inline table syntax This performs a pass over the docs, touching up sections in a few places and also moving everything to using inline table syntax by default (the favorted way to add a dependency) --- src/doc/build-script.md | 12 +++---- src/doc/guide.md | 17 +++++----- src/doc/manifest.md | 71 +++++++++++++++-------------------------- 3 files changed, 39 insertions(+), 61 deletions(-) diff --git a/src/doc/build-script.md b/src/doc/build-script.md index 8e28e2600..7d98d2f90 100644 --- a/src/doc/build-script.md +++ b/src/doc/build-script.md @@ -80,8 +80,8 @@ Dependencies are declared through the `build-dependencies` section of the manifest. ```toml -[build-dependencies.foo] -git = "https://github.com/your-packages/foo" +[build-dependencies] +foo = { git = "https://github.com/your-packages/foo" } ``` The build script **does not** have access to the dependencies listed in the @@ -424,11 +424,11 @@ authors = ["..."] links = "git2" build = "build.rs" -[dependencies.libssh2-sys] -git = "https://github.com/alexcrichton/ssh2-rs" +[dependencies] +libssh2-sys = { git = "https://github.com/alexcrichton/ssh2-rs" } -[target.x86_64-unknown-linux-gnu.dependencies.openssl-sys] -git = "https://github.com/alexcrichton/openssl-sys" +[target.x86_64-unknown-linux-gnu.dependencies] +openssl-sys = { git = "https://github.com/alexcrichton/openssl-sys" } # ... ``` diff --git a/src/doc/guide.md b/src/doc/guide.md index e714ac9b7..aed81ae95 100644 --- a/src/doc/guide.md +++ b/src/doc/guide.md @@ -233,8 +233,8 @@ name = "hello_world" version = "0.1.0" authors = ["Your Name "] -[dependencies.color] -git = "https://github.com/bjz/color-rs.git" +[dependencies] +color = { git = "https://github.com/bjz/color-rs.git" } ``` This project has a single dependency, on the `color` library. We've stated in @@ -251,9 +251,8 @@ builds. This would be bad, because we want reproducible builds. We could fix this problem by putting a `rev` line in our `Cargo.toml`: ```toml -[dependencies.color] -git = "https://github.com/bjz/color-rs.git" -rev = "bf739419e2d31050615c1ba1a395b474269a4" +[dependencies] +color = { git = "https://github.com/bjz/color-rs.git", rev = "bf739419" } ``` Now, our builds will be the same. But, there's a big drawback: now we have to @@ -270,8 +269,8 @@ name = "hello_world" version = "0.1.0" authors = ["Your Name "] -[dependencies.color] -git = "https://github.com/bjz/color-rs.git" +[dependencies] +color = { git = "https://github.com/bjz/color-rs.git" } ``` Cargo will take the latest commit, and write that information out into our @@ -435,8 +434,8 @@ This will create a new folder `hello_utils` inside of which a `Cargo.toml` and up `hello_world/Cargo.toml` and add these lines: ```toml -[dependencies.hello_utils] -path = "hello_utils" +[dependencies] +hello_utils = { path = "hello_utils" } ``` This tells Cargo that we depend on a crate called `hello_utils` which is found diff --git a/src/doc/manifest.md b/src/doc/manifest.md index c79913587..c8ee1e8ad 100644 --- a/src/doc/manifest.md +++ b/src/doc/manifest.md @@ -116,52 +116,42 @@ search ranking of a crate. It is highly discouraged to omit everything in a published crate. -# The `[dependencies.*]` Sections +# The `[dependencies]` Section -You list dependencies using `[dependencies.]`. For example, if you -wanted to depend on both `hammer` and `color`: +You list dependencies using keys inside of the `[dependencies]` section. For +example, if you wanted to depend on `hammer`, `color`, and `geometry`: ```toml [package] # ... -[dependencies.hammer] -version = "0.5.0" # optional -git = "https://github.com/wycats/hammer.rs" - -[dependencies.color] -git = "https://github.com/bjz/color-rs" - -[dependencies.geometry] -path = "crates/geometry" -``` - -You may prefer to use TOML's inline table syntax: - -```toml [dependencies] hammer = { version = "0.5.0", git = "https://github.com/wycats/hammer.rs" } color = { git = "https://github.com/bjz/color-rs" } geometry = { path = "crates/geometry" } ``` -You can specify the source of a dependency in one of two ways at the moment: +You can specify the source of a dependency in a few ways: -* `git = ""`: A git repository with a `Cargo.toml` in its root. The - `rev`, `tag`, and `branch` options are also recognized to use something other - than the `master` branch. +* `git = ""`: A git repository with a `Cargo.toml` inside it (not + necessarily at the root). The `rev`, `tag`, and `branch` options are also + recognized to use something other than the `master` branch. * `path = ""`: A path relative to the current `Cargo.toml` - with a `Cargo.toml` in its root. + pointing to another directory with a `Cargo.toml` and an associated package. +* If `path` and `git` are omitted, then a dependencies will come from crates.io + and use the `version` key to indicate the version requirement. -Dependencies from crates.io are not declared with separate sections: +Dependencies from crates.io can also use a shorthand where just the version +requirement is specified: ```toml [dependencies] hammer = "0.5.0" -color = "0.6.0" +color = "> 0.6.0, < 0.8.0" ``` -The syntax of the requirement strings is described in the [crates.io guide](crates-io.html#using-crates.io-based-crates). +The syntax of the requirement strings is described in the [crates.io +guide](crates-io.html#using-crates.io-based-crates). Platform-specific dependencies take the same format, but are listed under the `target.$triple` section: @@ -179,7 +169,8 @@ openssl = "1.0.1" native = { path = "native/x86_64" } ``` -If you're using a target file, quote the full path and file name: +If you're using a custom target specification, quote the full path and file +name: ```toml [target."x86_64/windows.json".dependencies] @@ -303,29 +294,17 @@ route-recognizer = "=2.1.0" # A list of all of the optional dependencies, some of which # are included in the above "features". They can be opted # into by apps. -[dependencies.jquery] -version = "1.0.2" -optional = true - -[dependencies.uglifier] -version = "1.5.3" -optional = true - -[dependencies.bcrypt] -version = "*" -optional = true - -[dependencies.civet] -version = "*" -optional = true +jquery = { version = "1.0.2", optional = true } +uglifier = { version = "1.5.3", optional = true } +bcrypt = { version = "*", optional = true } +civet = { version = "*", optional = true } ``` To use the package `awesome`: ```toml -[dependencies.awesome] -version = "1.3.5" -features = ["secure-password", "civet"] +[dependencies] +awesome = { version = "1.3.5", features = ["secure-password", "civet"] } # do not include the default features, and optionally # cherry-pick individual features @@ -396,9 +375,9 @@ In almost all cases, it is an antipattern to use these features outside of high-level packages that are designed for curation. If a feature is optional, it can almost certainly be expressed as a separate package. -# The `[dev-dependencies.*]` Sections +# The `[dev-dependencies]` Section -The format of this section is equivalent to `[dependencies.*]`. Dev-dependencies +The format of this section is equivalent to `[dependencies]`. Dev-dependencies are not used when compiling a package for building, but are used for compiling tests and benchmarks. -- 2.30.2